home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / src / alib / csup / clib / autodocs.asm next >
Assembly Source File  |  1994-02-14  |  8KB  |  248 lines
  1.  
  2. ******* amiga.lib/AddTOF *****************************************************
  3. *
  4. *   NAME
  5. *    AddTOF - add a task to the VBlank interrupt server chain.
  6. *
  7. *   SYNOPSIS
  8. *    AddTOF(i,p,a);
  9. *
  10. *    VOID AddTOF(struct Isrvstr *, APTR, APTR);
  11. *
  12. *   FUNCTION
  13. *    Adds a task to the vertical-blanking interval interrupt server
  14. *    chain. This prevents C programmers from needing to write an
  15. *    assembly language stub to do this function.
  16. *
  17. *   INPUTS
  18. *    i - pointer to an initialized Isrvstr structure
  19. *    p - pointer to the C-code routine that this server is to call each
  20. *        time TOF happens
  21. *    a - pointer to the first longword in an array of longwords that
  22. *        is to be used as the arguments passed to your routine
  23. *        pointed to by p.
  24. *
  25. *   SEE ALSO
  26. *    RemTOF(), <graphics/graphint.h>
  27. *
  28. ******************************************************************************
  29.  
  30.  
  31. ******* amiga.lib/RemTOF *****************************************************
  32. *
  33. *   NAME
  34. *    RemTOF - remove a task from the VBlank interrupt server chain.
  35. *
  36. *   SYNOPSIS
  37. *    RemTOF(i);
  38. *
  39. *    VOID RemTOF(struct Isrvstr *);
  40. *
  41. *   FUNCTION
  42. *    Removes a task from the vertical-blanking interval interrupt server
  43. *    chain.
  44. *
  45. *   INPUTS
  46. *    i - pointer to an Isrvstr structure
  47. *
  48. *   SEE ALSO
  49. *    AddTOF(), <graphics/graphint.h>
  50. *
  51. ******************************************************************************
  52.  
  53.  
  54. ******* amiga.lib/FastRand ***************************************************
  55. *
  56. *   NAME
  57. *    FastRand - quickly generate a somewhat random integer
  58. *
  59. *   SYNOPSIS
  60. *    number = FastRand(seed);
  61. *
  62. *    ULONG FastRand(ULONG);
  63. *
  64. *   FUNCTION
  65. *    Seed value is taken from stack, shifted left one position,
  66. *    exclusive-or'ed with hex value $1D872B41 and returned.
  67. *
  68. *   INPUTS
  69. *    seed - a 32-bit integer
  70. *
  71. *   RESULT
  72. *    number - new random seed, a 32-bit value
  73. *
  74. *   SEE ALSO
  75. *    RangeRand()
  76. *
  77. ******************************************************************************
  78.  
  79.  
  80. ******* amiga.lib/RangeRand **************************************************
  81. *
  82. *   NAME
  83. *    RangeRand - generate a random number within a specific integer range
  84. *
  85. *   SYNOPSIS
  86. *    number = RangeRand(maxValue);
  87. *
  88. *    UWORD RangeRand(UWORD);
  89. *
  90. *   FUNCTION
  91. *    RangeRand() accepts a value from 0 to 65535, and returns a value
  92. *    within that range.
  93. *
  94. *    maxValue is passed on stack as a 32-bit integer but used as though
  95. *    it is only a 16-bit integer. Variable named RangeSeed is available
  96. *    beginning with V33 that contains the global seed value passed from
  97. *    call to call and thus can be changed in a program by declaring:
  98. *
  99. *      extern ULONG RangeSeed;
  100. *
  101. *   INPUTS
  102. *    maxValue - the returned random number will be in the range
  103. *               [0..maxValue-1]
  104. *
  105. *   RESULT
  106. *    number - pseudo random number in the range of [0..maxValue-1].
  107. *
  108. *   SEE ALSO
  109. *    FastRand()
  110. *
  111. ******************************************************************************
  112.  
  113.  
  114. ******* amiga.lib/printf *****************************************************
  115. *
  116. *   NAME
  117. *    printf - print a formatted output line to the standard output.
  118. *
  119. *   SYNOPSIS
  120. *    printf(formatstring [,value [,values] ] );
  121. *
  122. *   FUNCTION
  123. *    Format the output in accordance with specifications in the format
  124. *    string.
  125. *
  126. *   INPUTS
  127. *    formatString - a C-language-like NULL-terminated format string,
  128. *               with the following supported % options:
  129. *
  130. *      %[flags][width][.limit][length]type
  131. *
  132. *        $     - must follow the arg_pos value, if specified
  133. *      flags   - only one allowed. '-' specifies left justification.
  134. *      width   - field width. If the first character is a '0', the
  135. *                field is padded with leading 0s.
  136. *        .     - must precede the field width value, if specified
  137. *      limit   - maximum number of characters to output from a string.
  138. *                (only valid for %s or %b).
  139. *      length  - size of input data defaults to word (16-bit) for types c,
  140. *            d, u and x, 'l' changes this to long (32-bit).
  141. *      type    - supported types are:
  142. *                      b - BSTR, data is 32-bit BPTR to byte count followed
  143. *                          by a byte string. A NULL BPTR is treated as an
  144. *                  empty string. (V36)
  145. *                      d - signed decimal
  146. *              u - unsigned decimal
  147. *                      x - hexadecimal with hex digits in uppercase
  148. *              X - hexadecimal with hex digits in lowercase
  149. *                      s - string, a 32-bit pointer to a NULL-terminated
  150. *                          byte string. A NULL pointer is treated
  151. *                          as an empty string.
  152. *                      c - character
  153. *
  154. *    value(s) - numeric variables or addresses of null-terminated strings
  155. *               to be added to the format information.
  156. *
  157. *   NOTE
  158. *    The global "_stdout" must be defined, and contain a pointer to
  159. *    a legal AmigaDOS file handle. Using the standard Amiga startup
  160. *    module sets this up. In other cases you will need to define
  161. *    stdout, and assign it to some reasonable value (like what the
  162. *    dos.library/Output() call returns). This code would set it up:
  163. *
  164. *        ULONG stdout;
  165. *        stdout=Output();
  166. *
  167. *   BUGS
  168. *    This function will crash if the resulting stream after
  169. *    parameter substitution is longer than 140 bytes.
  170. *
  171. ******************************************************************************
  172.  
  173.  
  174. ******* amiga.lib/sprintf ****************************************************
  175. *
  176. *   NAME
  177. *    sprintf - format a C-like string into a string buffer.
  178. *
  179. *   SYNOPSIS
  180. *    sprintf(destination formatstring [,value [, values] ] );
  181. *
  182. *   FUNCTION
  183. *    Performs string formatting identical to printf, but directs the output
  184. *    into a specific destination in memory. This uses the ROM version
  185. *    of printf (exec.library/RawDoFmt()), so it is very small.
  186. *
  187. *    Assembly programmers can call this by placing values on the
  188. *    stack, followed by a pointer to the formatstring, followed
  189. *    by a pointer to the destination string.
  190. *
  191. *   INPUTS
  192. *    destination - the address of an area in memory into which the
  193. *              formatted output is to be placed.
  194. *    formatstring - pointer to a null terminated string describing the
  195. *                   desired output formatting (see printf() for a
  196. *               description of this string).
  197. *    value(s) - numeric information to be formatted into the output
  198. *           stream.
  199. *
  200. *   SEE ALSO
  201. *     printf(), exec.library/RawDoFmt()
  202. *
  203. ******************************************************************************
  204.  
  205.  
  206. ******* amiga.lib/stdio ******************************************************
  207. *
  208. *   NAMES
  209. *    fclose    - close a file
  210. *    fgetc    - get a character from a file
  211. *    fprintf    - format data to file (see printf())
  212. *    fputc    - put character to file
  213. *    fputs    - write string to file
  214. *    getchar    - get a character from stdin
  215. *    printf    - put format data to stdout (see exec.library/RawDoFmt)
  216. *    putchar    - put character to stdout
  217. *    puts    - put string to stdout, followed by newline
  218. *
  219. *   FUNCTION
  220. *    These functions work much like the standard C functions of the same
  221. *    names. The file I/O functions all use non-buffered AmigaDOS
  222. *    files, and must not be mixed with the file I/O of any C
  223. *    compiler. The names of these functions match those found in many
  224. *    standard C libraries, when a name conflict occurs, the function is
  225. *    generally taken from the FIRST library that was specified on the
  226. *    linker's command line.  Thus to use these functions, specify
  227. *    the amiga.lib library first.
  228. *
  229. *    To get a suitable AmigaDOS FileHandle, the dos.library/Open() or
  230. *    dos.library/Output() functions must be used.
  231. *
  232. *    All of the functions that write to stdout expect an appropriate
  233. *    FileHandle to have been set up ahead of time. Depending on
  234. *    your C compiler and options, this may have been done by the
  235. *    startup code.  Or it can be done manually
  236. *
  237. *    From C:
  238. *        extern ULONG stdout;
  239. *        /* Remove the extern if startup code did not define stdout */
  240. *        stdout=Output();
  241. *
  242. *    From assembly:
  243. *        XDEF    _stdout
  244. *        DC.L    _stdout    ;<- Place result of dos.library/Output() here.
  245. *
  246. ******************************************************************************
  247.  
  248.